home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / amok_lha / amok13.lha / Rows / Rows.doc < prev    next >
Text File  |  1993-08-15  |  6KB  |  169 lines
  1. ======================================================================
  2. Documentation for module "Rows"
  3. Author: Nicolas Benezan, Postwiesenstr. 2, 7000 Stuttgart 60, Germany
  4. supported by Michael Frieß [mif] (thanks !!!)
  5. ======================================================================
  6.  
  7. Copyright remarks
  8. ­­­­­­­­­­­­­­­­­
  9.  
  10. (C) Copyright 1988 by Nicolas Benezan. All rights reserved.
  11. The whole package (source, documentation and code) is donated to
  12. public domain and may be copied and redistributed providing that...
  13.  
  14. * my name and this copyright remark and
  15. * the completeness of the package remain intact,
  16. * it's distributet for non-profit only.
  17.  
  18. Commercial use without my explicit, written permission is not
  19. allowed. Contact me to get it and, perhaps, to pay some fee.
  20.  
  21. Improvements and new ideas are welcome, as long as the changes are
  22. well documented inline and in the documentation files. I would like
  23. to know, if you make major changes and repost it.
  24.  
  25.  
  26. Contents
  27. ­­­­­­­­
  28. * Package
  29. * Introduction
  30. * Generic Data Types
  31. * New Data Type "Row"
  32. * Row-Operators
  33. * Test module
  34.  
  35.  
  36. Package
  37. ­­­­­­­
  38. The whole package "Rows" consist of following files:
  39.  
  40.   Rows.doc        This documentation file
  41.   Rows.dok        German documentation
  42.   Rows.def        Definition module
  43.   Rows.mod        Implementation module
  44.   Rows.sym        Symbol file
  45.   Rows.obj        Compiled object code
  46.   RowDemo.mod     Test module
  47.   RowDemo.obj     Compiled test module
  48.   RowDemo         Executable test module
  49.  
  50.  
  51. Introduction
  52. ­­­­­­­­­­­­
  53. Often, you need basic data structures and operations on
  54. them, which are not implemented in Modula-II.
  55. However, Modula-II supports development of generic data types.
  56. The best known example of generic data type is "File".
  57. You can import "File" and procedures operating on it from
  58. system module "FileSystem".
  59. The one thing, you have to know, is the abstract concept
  60. of files, not the implementation.
  61. This module offers a generic type "Row".
  62.  
  63.  
  64. Generic Data Types
  65. ­­­­­­­­­­­­­­­­­­
  66. In Modula-II (as well as in most other high-level languages)
  67. you can create new types by declaration. New types can consist
  68. of structures and components, but every component type has to
  69. be known before declaration of the new type (either by
  70. declaration or as an simple data type - for example BOOLEAN).
  71. Modula-II knows four structure methods for building new types:
  72. ARRAY, SET, RECORD and POINTER.
  73. With last one you can create a large scale of new types.
  74. For example a list:
  75.   TYPE  listptr = POINTER TO list;
  76.         list    = RECORD
  77.                    item : T0;
  78.                    next : listptr
  79.                   END;
  80.  
  81. To use this list you develop some procedures for initialization,
  82. insert an item, read an item and so on. All procedures are
  83. independent of your component type T0, but your type "list"
  84. depends on it.
  85. A generic data type now can be used with ANY (!) component
  86. type!
  87. The concept of Modula-II supports development of modules that
  88. present data capsules exporting a generic type and procedures
  89. working on it.
  90. But this support is not perfect, you have to avoid type
  91. checking of parameters. Only the size of parameters is checked.
  92. Data can have equal or smaller (think of string constants)
  93. size than the size declared by Dim().
  94. If you want to know more about principles of generic data types
  95. and data capsules, you should refer to the module "List" and
  96. documentation by Michael Frieß [mif] ("List" and some other generic
  97. data types are included in the AmokLib and Amok-PD-Disk #7).
  98.  
  99.  
  100. New Data Type "Row"
  101. ­­­­­­­­­­­­­­­­­­­
  102. "Row" is a data type somwhere in between ARRAYs and dynamically
  103. linked lists [1]. ARRAYs are declared statically, this means,
  104. their size and the size of each component has to be known before
  105. compiling. Lists (components linked by pointers) are fully dynamic.
  106. Your programm can insert and remove components while running and
  107. the list grows and shrinks in memory.
  108. Rowss are a sort of compromise. They are declared at run time, so
  109. their component and total size needn't be known before compiling.
  110. But once they are there, they can't change size. On the one hand,
  111. this is a disadvantage but on the other hand you have random access
  112. to any components of a Row and don't have to scan the list
  113. sequentially. The components of a Row are referenced by index
  114. (like ARRAYs) and not by pointers (like lists). If you have to
  115. access completely different parts of the data very often, your code
  116. will execute much faster using Rows than using lists.
  117.  
  118.  
  119. Row-Operators
  120. ­­­­­­­­­­­­­
  121. In following operators and their abstract intention are listed.
  122. You can find more details in definition module.
  123.  
  124. * Dim()
  125.   Declares and initialize a new Row for further use.
  126.  
  127. * Discard()
  128.   Discard a Row, i.e. all elements and the Row itself, and deallocates
  129.   memory.
  130.  
  131. * Write()
  132.   Copies data TO an element of a Row (the corresponding ARRAY-assignment
  133.   would be Array[index]:=Data)
  134.  
  135. * Read()
  136.   Copies data FROM an element of a Row (the corresponding ARRAY-assignment
  137.   would be Data:=Array[index])
  138.  
  139. * High() and CompSize()
  140.   If you have Procedures which have Rows as parameters you might wish
  141.   something like HIGH() for ARRAYs to handle Rows of different size.
  142.   You can find out the maximum index of a Row with High() and its
  143.   component size with CompSize().
  144.  
  145. * Import() and Export()
  146.   These Procedures help you to Read/Write Rows from/to disk-(or other
  147.   Dos-) files. They provide an interface to the data buffer of a Row in
  148.   memory. But be careful ! You are responsible to do correct size and
  149.   compatiblity checking. Because of the restrictions of Modula-2
  150.   the Module Rows can't do it for you.
  151.  
  152. If you want to know more about procedures listed above and the meaning of
  153. their parameters, please refer to the definition module.
  154.  
  155.  
  156. Test module
  157. ­­­­­­­­­­­
  158. The module "RowDemo" tests and demonstrates Rows and their usage.
  159. It Dim()s a Row with a random number of elements, then it fills the Row
  160. with random numbers and finally it sorts the numbers.
  161. I used the well known "HeapSort" algorithm in which I only changed
  162. ":="-assignments into Read()/Write()-statements (because of Rows).
  163. If you watch the free memory display of the workbench while running
  164. RowDemo you'll see that Rows consume more or less memory depending on
  165. their size.
  166. (Note: I don't want to demonstrate speed of HeapSort but the usage of
  167. Rows. So do not complain about its speed. I know it could be faster.)
  168.  
  169.